PHASE 9: Documentation Integrity Audit & AI Coding Logging Mode Module

Part 1: Documentation Claims Cleanup

Audit all project documentation (README.md, docs/, CLI help, code comments) and remove or rewrite any unsubstantiated claims about:

• Performance metrics (framerates, latency numbers, "X ms", "Y FPS")
• Absolute compatibility ("works everywhere", "never breaks")
• Feature guarantees not backed by automated tests

Replace with evidence-based statements or mark as "aspirational/untested".

Add new "Reality vs. Claims" section to README documenting what is proven vs. aspirational.

Part 2: AI Coding Logging Mode - Standalone Module

Create a self-contained AI Coding Logging Module that can be integrated into all subsystems.

Module Files:

• src/ai_logging.h - Public API and macros
• src/ai_logging.c - Implementation
• src/ai_logging_internal.h - Internal types (optional, for struct definitions)

Module Features:

1. Initialization & Configuration

   • ai_logging_init(rootstream_ctx_t *ctx) - Initialize module, detect --ai-coding-logs CLI flag and AI_COPILOT_MODE env var
   • ai_logging_is_enabled(rootstream_ctx_t *ctx) - Check if logging is active
   • ai_logging_set_enabled(rootstream_ctx_t *ctx, bool enabled) - Programmatic toggle
   • ai_logging_shutdown(rootstream_ctx_t *ctx) - Cleanup, print summary if enabled

2. Logging API

   • ai_log(const char *module, const char *fmt, ...) - Core logging function (compiles to NOP if disabled)
   • Convenience macros: AI_LOG_MODULE(fmt, ...) per module for brevity

3. Structured Output

   • Format: [AICODING][module][tag] message
   • Example: [AICODING][capture][init] DRM backend selected
   • Goes to stderr by default
   • Optional file output support (e.g., --ai-coding-logs=/path/to/logfile)

4. Performance Safeguards

   • Zero overhead when disabled (macro compiles out)
   • Minimal overhead when enabled (single fprintf per call)
   • Optional: Build flag to compile out entirely (ENABLE_AI_LOGGING)

5. Integration Points

   • Module context flag: rootstream_ctx_t.ai_logging_enabled
   • Module init checks CLI args and env vars automatically
   • All subsystems can call ai_log() without knowing implementation details

6. Startup Banner

   • When enabled, print warning to stderr about verbose logging
   • Include hint to disable with AI_COPILOT_MODE=0

Integration with Existing Code:

• Modify src/main.c to call ai_logging_init() early in startup
• Add --ai-coding-logs[=FILE] CLI argument parsing to main
• Optionally integrate with existing logging/diagnostics module if present

Example Usage in Subsystems:

In src/capture_drm.c:

ai_log("capture", "init: attempting DRM/KMS backend");
ai_log("capture", "init: DRM device=%s fd=%d", device_path, fd);
ai_log("capture", "fallback: DRM failed, trying X11");

In src/encode_vaapi.c:

ai_log("encode", "init: available backends=[NVENC:%d, VAAPI:%d, x264:%d]", 
       has_nvenc, has_vaapi, has_x264);
ai_log("encode", "init: selected backend=VAAPI");

Documentation:

• Add docs/AI_LOGGING_MODE.md with:

  • Feature overview
  • Activation methods (CLI, env, API)
  • Example log output
  • How to use with Copilot/Claude
  • Sample troubleshooting workflows

• Update README.md:

  • Add "AI Coding Logging Mode" section
  • Link to docs/AI_LOGGING_MODE.md
  • Include example: AI_COPILOT_MODE=1 ./rootstream --service

Success Criteria:

• ✅ AI logging module is self-contained and easy to integrate
• ✅ Zero performance impact when disabled
• ✅ Toggleable via CLI, env var, and API
• ✅ Structured, machine-readable output for AI agents
• ✅ Clear warning banner when active
• ✅ Can be used by all subsystems without code duplication
• ✅ Documentation covers activation and use cases
• ✅ All unsubstantiated performance claims removed from README/docs